Copyright: Refs 7.8 Help, ® TJR Cutts, 1993-5


Refs Help Contents
Contents

Introduction (Hello, Good Evening, and Welcome!)

How to do it (for the uninitiated)

Technical notes (for programmers and the curious)

Installation instructions for shared network volumes

Licence information (for everyone)

About the author (how to contact me)

Frequently Asked Questions (read this before mailing me)

Version History (what's new or fixed in recent versions)

All trademarks are the property of their respective owners.


Introduction

Welcome to Refs, a program for creating, maintaining and searching academic reference databases or other bibliographic data.

Refs provides a user-friendly interface for handling reference databases.  It provides the following features:

1.	Multiple Document Interface support allowing bibliography construction and searches to be made from multiple source files, and drag-and-drop between files.

2.	Import and export databases from/to other formats.

3.	Create bibliographies which can be printed, saved as text files, refer files, or pasted into other applications.

4.	Store data in the following fields:  Author(s), Title, Date, Journal, Book Title, Report, Issuer, Editor, City, Volume, Number, Pages, Keywords and Abstract.

5.	Single or multi-column display options.

6.	Easy Cardfile-like keyboard operation.

7.	Flexible sorting on multiple fields.

8.	International support for languages other than English.

The Interface

There are four main window types in Refs

Database windows

Each database window contains a single database file.  References can be freely copied and/or dragged between file windows, and from search windows to others.  References can also be dragged to the bibliography window, if it already exists.

Bibliography window:

This is where the bibliography is displayed, in either database or text format, and from where it can be saved to disk or copied to the clipboard.  When in text format, it is displayed with the current printer font, and can be edited.

Reference form:

This appears when you view or edit a reference.  It displays the authors and date of the reference in the title bar, and contains edit fields for the various fields of the reference.  See Editing references

Author form:

This is used to edit the author or date fields of the reference that make up its title in the reference form, and also to specify the reference type (book or journal).

Further information

There is World Wide Web page dedicated to Refs which I keep updated with plans and latest developments.  Example source code for import filters is also kept there.  If you have a WWW browser, you will find Refs information at:

http://chiark.chu.cam.ac.uk:81/refs/refs.html

This should be available until about October 1996.


About
About the author

If you find a bug in Refs, or have any suggestions to make, please e-mail me directly at:

tjrc1@mole.bio.cam.ac.uk

or by snail mail:

NB:  The following address will only be valid until March 1996.  After this date e-mail only, please.  To be safe, e-mail me first and find out what my latest address is.

T. J. R. Cutts

Department of Zoology

Downing St

Cambridge

UK

Important: Please note that Refs is a personal project.  It has nothing to do with the Cancer Research Campaign, the DNA Repair Research Group, or Cambridge University, so do not send them any mail concerning it!

When reporting a bug, should you be unlucky enough to find one, please tell me the following:

a)  What you were attempting to do; if the bug is not reproducible I won't be able to find it!  Give as many details as you can.

b)  What the error was (Runtime error numbers if they occur)  All details are important.

c)  Program version number.  Exact version numbers are bound into the main program files, and can be read with File Manager.  Some of them are displayed by the Help, About dialog box.

d)  Anything else that might be even remotely relevant

If at all possible, use the world-wide web bug report form I have created.  You can find this at:

http://chiark.chu.cam.ac.uk:81/refs/bug.html


Licence
Licence and Registration Information

Important:

This software comes under no warranty whatsoever, expressed or implied.  The author cannot be held responsible for any loss occurring as a result of the use of this program, directly or indirectly.  The author makes no guarantees as to the suitability of this software for any purpose.

Having got the nasty disclaimer out of the way, here's stuff you really might want to know:

There are three forms of Refs you may be running.

1)	The unregistered version

2)	A version registered on your behalf and supplied to you by another company

3)	A fully registered copy for an individual.

Most of this information applies to users in categories 1 and 3, although there is some information for category 2 users at the end of this topic.

If you have downloaded a copy from the Internet or a public BBS that is not category 1, you (and that site) are committing software piracy.  Please report any such piracy to the author.

This piece of software, unregistered, is fully functional, but time limited. After it has been installed on your machine for 30 days it will remind you to pay, and the time this warning remains on-screen for 30 seconds.  This should give you some time to evaluate its usefulness for you, without completely locking you out when the time runs out.

You are licensed to copy and distribute the unregistered version freely as long as you distribute the complete distribution and make no charge other than reasonable duplication costs.

Registration:

Registration gets you:

i)	A registration number to remove the nag screen.

ii)	Your registration fee covers a single-user copy of the program.  You may not distribute the registered version to any other persons.  Multiple licences are available at a discount, see below.

iii)	Those with e-mail addresses will receive notification of upgrades and so on, and the chance to test new versions before they are released.  You also get your say in what gets added and/or changed in the next version.  Many features, such as the 'Copy formatted reference' menu item, have been added after suggestions from users like you!

How much does it cost?  See the Order Form

To register, print out the order form and mail it to me.  Once you receive your registration code from me, you can enter this into the program.  If you are over the 30 day limit, the Register button will allow you to do this.  If you are under the 30 day limit, you can choose Register from the Help menu.

When registering, please send me an e-mail address if you possibly can so that I can mail updates to you.

My address can be found in the about section, as can information about the current state of development and plans for future versions.


Order Form
Refs Order Form

Please note that I may have moved house by the time you read this (my life is a little chaotic at the moment).  To avoid problems with cheques getting lost in the post or sent to the wrong address, please send me an e-mail message at tjrc1@mole.bio.cam.ac.uk first to confirm details, if at all possible.

Name:___________________________________________

Company:________________________________________

E-mail:_________________________________________

Refs Version:___________________________________

          No. of Refs licenses:_________________

No. of licences	Each (UKP)	Each (US$)
1-4 licences	£29.99	$47.99
5-25 licences	£24.99	$39.99
26-99 licences	£19.99	$31.99
Upgrade from custom versions	£20.00	N/A

Sub Total_______________________________________

Payment: [ ] Eurocheque (Sterling)

         [ ] International Money Order (Sterling)

         [ ] Sterling cheque drawn on a UK bank.

         [ ] Cheque in US dollars (see below).

         [ ] Cash

Surcharge for payment in US$  ($8.00):   _______

                             GRAND TOTAL:_______

Signed:_________________________________________

Date:___________________________________________


History
Version History

Refs 7.8

Export functionality added.  Commonly used keyword list added.  Ability to edit bibliography format lines added.  Changed from distributing a demo version to distributing a time-limited version.  Link mode removed (it's broken, and no-one seems to use it anyway).  First version of Refs also available as a native 32 bit program for Windows NT and Windows 95.  Windows 95/NT version has a new toolbar.

Refs 7.72

Bugfixes

Refs 7.7

New check-box to set a window searchable.  Various bug fixes.  The arrow buttons in the Edit form no longer cause the window to be closed and re-opened (should save some time!).  Status bar now uses SYSTEM_FONT instead of ANSI_VAR_FONT so the status bar now works with non-Roman character sets (such as Japanese).

Refs 7.62

Bugfixes

Refs 7.6 (10th February 1995)

Improvements made to the sorting of names.  Formatting code extended again (test for field not present, and prefix and suffix fields).

Refs 7.57 (1st February 1995)

REFS.INI may now be found in the WINDOWS directory, making Refs rather more network-friendly.

Refs 7.56  (26th January 1995)

By popular request, the status bar now always shows you how many references are in the active window.

Refs 7.55  (25th January 1995)

Bugfixes.

Refs 7.54  (21st January 1995)

Bibliography format lines now allow nested formats.  Refs now remembers if the bibliography was last displayed formatted. If a journal and a book have the same authors, title etc., Refs no longer considers them identical.  If a search returns no results, the empty search window is automatically destroyed.

Refs 7.53

Bugfixes.  Made refs check book title field for comparison if title field is empty.

Refs 7.51

Bugfixes.

Refs 7.5

Major internal reworking of database to increase memory efficiency.  Printing, at last!  More intelligent import filter loading.  Fonts used for printing and database windows are user-selectable.  Searches now create a new window and all open windows can be searched automatically.  Loading, saving and resorting files no longer grabs control of the machine so aggressively.  Drag and drop between database windows has been implemented.  If no author is found in a reference, the editor's name will be displayed instead, if supplied. Confirmation options moved to a separate dialog box.

Refs 7.42 (15th July 1994)

Refs now remembers the last four files you opened or saved, and adds them to the File menu so that you can quickly re-open them.  Mats wrote an import DLL for Current Contents Reference Manager files (IMPCCREF.DLL), and updated IMPCHEM.DLL too.

Refs 7.41 (17th April 1994)

Bugfixes.

Refs 7.4

The import DLL syntax has been changed.  DLLs written for earlier versions of Refs will not work with this version, and will crash the program.  The interface now uses MMSYSTEM buffered file I/O.  This should make it much easier for C/C++ programmers to write DLLs for Refs, whereas before it was only really possible in Pascal.  MedLine and BIDS filters updated to new format.  The BIDS filter should now work with BIDS-Embase searches properly, and import their Abstracts.  Minor changes to MedLine DLL to work properly with some MedLine formats.  Fixed bibliography syntax to distinguish between B, R and J fields.  New item 'Copy formatted reference' added to editing dialog Edit menu, which copies the entire reference to the clipboard according to the current bibliography format setting. Refs now remembers the size you last selected for the editing dialog and uses it.

Refs 7.3 (19th January 1994)

All resources removed and placed in a separate DLL, to allow for easy creation of future versions in other languages.  Please see Refs and other languages. You can specify how Refs sorts its display.  Maximum length of bibliography format lines increased from 63 to 255 characters.  Bibliography format allows insertion of line breaks in formatted references, using the C-style '\n' notation.  Status line fixed to respond to menu changes properly.  File import dialog greys the Options... and OK buttons if a bad REFS.INI entry is selected.  The main editing dialog has been made slightly smaller.  It should now fit 640x480 screens better.

Refs 7.2

Buttons to move to next/previous references.  Editor field now allows multiple entries in the same way as the Authors field.  If the %T title field is empty, the Journal/book title field is shown instead when titles are being shown in the main list.  The drop down journal list can be edited in the program rather than directly in REFS.INI.  It is now context sensitive depending on reference type.  Main editing window now resizeable for those of us with larger screens who want more room!  Mats again updated IMPCHEM.DLL.

Refs 7.1

3D look now provided by CTL3D.DLL rather than BWCC.DLL, for reasons of consistency with Chicago (still over two years away when 7.1 was released) and Cairo. Case sensitivity has been removed during sorting.  Sorting now uses the language driver.  Mats vastly improved IMPCHEM.DLL

Refs 7.0

New MDI Interface, and associated cut/paste between windows.  The Edit form changed considerably:  1) 'Journal title' box now a drop down combo box to allow storing of frequently used journal names  2) New 'OK and New' button, for rapid entry of multiple references.  Bibliography menu removed (functions were either moved elsewhere or are obsolete).  The Bibliography is now consolidated in a single window, with formatted and list display toggle. Many file menu options are now obsolete and have been removed (such as 'save displayed references'). New IMPCHEM.DLL for Chemical Abstracts, written by Mats Valli.

Refs 6.1-6.3

Refinements of import DLL mechanism, and other changes that I've forgotten.

Refs 6.0 (22 July 1993)

Expandable foreign file import DLL support added.  Menu added to main editing window for mouse-based clipboard functions.  Cut/Copy/Paste/Undo are now more accessible for all field edit controls in this dialog box.

Refs 5.2

Changed handling of Author names and Keywords to make them more flexible.  Some minor changes to the appearance of some dialogs.  File loading and reference insertion much faster, at the expense of slightly more memory usage.

Refs 5.1 (10 June 1993)

Owner drawn list box obeys the colours specified in Control Panel, in the same way as File Manager.

Refs 5.0 (29 May 1993)

The first release of what I considered to be a finished program.  Consequently its status changed to shareware, and I changed the version numbering policy.  Maximum capacity of over 4 million references, rather than 16,380!  Main display changed to owner drawn list box.  As well as now having pretty icons, this also means that more entries are allowed in the list box, so larger searches can be performed.  Altered and improved bibliography formatting structures.

Refs 0.41

Small fixes to some incorrect behaviour in publisher and city edit controls, and also in multiple selections in the main window.

Refs 0.4  (7 May 1993)

Generic support for all % field tags, even those not explicitly found in editing dialog boxes.  Explicit support for book references added.

Refs 0.3  (1 May 1993)

Bibliography facilities added.  Ability to make multiple selections in main display.  Number in volume field support.

Refs 0.2  (21 April 1993)

Fairly major re-write, especially of file handling and internal data structure.  For compatibility reasons, converted to using ASCII UNIX refer file format.  Improved keyboard use.  Added keyword field support.  Added status bar descriptions of menu commands.  Expand/Narrow search added.  Added display options.

Refs 0.1  (October 1992)

Never publicly released, but anyway:

Stored data in a proprietary binary format.  Allowed searches to be made for specific references.

I found an old copy of this recently.  It's barely recognisable as the same program any more!


How To Do It
How do I do this?

How to...

Add a new reference

Edit a reference

Delete a reference

Manage your keyword list

Search for references

Create and manage a bibliography

Print a reference

Transfer information to other applications

Import references from a foreign file format

Add or remove import libraries

Copy or move references between open file windows

Customise Refs

Sort References

Toolbar Shortcuts


Toolbar shortcuts
The Toolbar

Like many Windows programs, Refs has a toolbar.  This is not available for users of Windows 3.1, but for Refs 16-bit users running Windows for Workgroups and all 32-bit Refs version users.

Refs for Windows 95 has ToolTips which show you what each button does by leaving the mouse pointer over the button for a second or so.  However, this facility is not available in Refs for Windows 3.1, so here is a summary of the toolbar buttons and their menu command and accelerator equivalents:

Tool	Accelerator	Menu Command

File, New

Ctrl+O	File, Open

Ctrl+S	File, Save

File, Print

Ctrl+X	Edit, Cut

Ctrl+C	Edit, Copy

Ctrl+V	Edit, Paste

F7	Reference, New

Ctrl+B	Reference, Add to bibliography

Options, display formatted bibliography

F3	Search, New Search

Search, Narrow search

Search, Expand search

Help, Contents


Copying/Moving references between files
Copying and moving references between open files

You might want to transfer references from one file to another, for example if you wanted to maintain separate databases on different topics whose subjects happened to overlap somewhat.  Or you might want to transfer references from an on-line search you just imported to an exiting Refs file.  This is easily accomplished with either the mouse or keyboard, as follows:

Keyboard:  Select the references you wish to copy or move, in a file window.  Then use Cut/Copy/Paste from the edit menu to copy or move the references to another file window.  This procedure does not use the clipboard, so you can't paste references into other applications this way, I'm afraid.

Mouse:	Select the references you wish to copy or move.  Then click on your selection with the right mouse button.  The cursor changes to a reference card, or a stack of them.  Now drag to the target window and release the mouse button.

By default, references are copied, not moved.  If you wish to move the references and remove them from the original file, hold down the shift key while dragging (specifically, the shift key must be down when you release the right mouse button).

You can set Refs to ask you for confirmation of mouse drag operations under the Options, Confirmation... command.

Drag and drop also works to the bibliography window, if it exists.


Using bibliographies
Creating and using a bibliography

The contents of the bibliography are maintained by the program regardless of closing, opening and creating new files, so you can easily compile a bibliography from several source databases.

Select the references you wish to add to the bibliography and choose Reference, Add to bibliography.  If the Bibliography was previously empty, a bibliography window will be created automatically.  The same command is also available in the reference editing window, and also as an icon in the toolbar in the 32-bit version of the program.

References currently in the bibliography are shown a different colour from the others.  In the bibliography window, different colouring is also used.  Coloured references are also to be found in a currently open file, whereas normal colouring indicates that the file this reference is from has been closed, or the reference has been deleted from that file.  Either way, the bibliography has the sole remaining copy of the reference in memory, and deleting it will be permanent.

To remove references from the bibliography, select the bibliography window.  You may now use Reference, Delete as usual to remove the references.  However, in this case the references are not removed from memory unless they are not from any of the currently open files.  If the deletion results in the bibliography becoming empty, the bibliography window is automatically destroyed.

To empty the bibliography, simply close the bibliography window.

The bibliography window can display its contents in two ways; either as a reference database very similar to normal database windows, or as formatted text for editing and copying to the clipboard.  You can toggle between these displays with the Options, Display formatted bibliography command.  This window displays your file in the currently selected printer font, so you can use this as a crude form of print preview.

Depending on the state of this toggle, you can save the bibliography contents as either a database or as a standard text file, using File, Save As.

New bibliography formats can be created and entered using Options, bibliography format.  See bibliography format syntax for details.


Adding/removing import DLLs
Adding/removing import/export filters

The Import/Export feature is designed to be easily expandable with new formats.  Covered so far are MedLine, BioSys, Current Contents, Chemical Abstracts, Refer and BIDS, although of these Refer is at present the only one with export capability.  This help file also contains information for programmers wishing to write their own import filters.  See Import filter Interface  for details.

Please note that Current Contents and Chemical Abstracts are currently only available as 16-bit filters, and will not work with the 32-bit version.

Letting Refs know about new filters is easily accomplished.  You don't need to do anything!  The filter should have the filetype of FLT.  Just copy it into your Refs directory, and Refs will find it automatically.


Importing other format databases
Importing/exporting other database formats

Refs can theoretically read references from any reference file format.  Each format needs to have an import filter written for it (such as BIDS.FLT), to deal with the foreign format.  Refs can deal with up to 32 foreign formats.  At present, I have written such filters only for BioSys, ISI (BIDS) and MedLine.  Filters for the Chemical Abstracts and Current Contents Reference Manager are also included in the 16-bit version of Refs, written by Mats Valli.

1.	Select File, Import... and a dialog will appear listing the available formats known to Refs.  This will look something like the following diagram.  Select a format, and choose OK.

2.	Some filters may have an options function.  If so, the Options button will be available to allow you to call this function.  This typically displays version information and allows you to modify the filter's behaviour.

3.	Choose OK.  Double-clicking the desired format will also close the dialog box, as if you'd selected it and then clicked OK.

4.	Select the file to import in the next dialog box.

5.	Refs will then import the file as well as the filter can manage.  Imports may well lose some information, depending on the capabilities of the format being imported.  The imported file will appear as a new database window.

Programmers wishing to write their own import filters are referred to the Import filter Interface section.


Finding a reference
How to find a reference

1.	Check whether the windows you want to search are searchable, and adjust as necessary.  This is done with the check-box in the bottom left of each database window.  If the box is checked the window will be searched.

2.	Select New search... from the Search menu, press F3, or choose the search toolbar button.

3.	From the Search By combo box choose the type of search you wish to perform.

4.	In the Search For box type the string you wish to search for.

5.	Use the two check-boxes to tell Refs whether to search case sensitively, and whether to search for all references except those satisfying your conditions.

6.	Choose OK.  A new window will then show all references matching your criteria.  This window will automatically be marked non-searchable, unless it is saved as a file later.  The title bar initially contains a description of how the references were found, until it is saved as a file, when it becomes a normal file window.

7.	You're not content with the results?  Too many references?  You can restrict the search, by now selecting  Search, Narrow search...  This will repeat steps 2-4, but this time will perform the search only on those references you found last time (i.e., those which are currently displayed).

Too few results?  What if you want those references with either DNA or RNA in the title?  You could search for NA, but this would turn up all sorts of junk.  Instead, search for DNA, then select Search, Expand search...  Again, this repeats steps 2-4, but this time search for RNA.  The existing search is kept and any new references found which are not already in the list are added to it.

Description of search criteria

When a search is made, the new window has the criteria used to find the references in its title bar.

Each criterion is contained in braces { } and combined by the symbols + and ,.

+	References in both sets (logical AND)

,	References in either set (logical OR)

In addition, the expression inside the braces may contain a ! which indicates that the search was for references that did not match the criteria.  A silly example:

{{ Author = "Fred" } + { Date = !"1991"}} , { Author = "Joe" }

This search now contains all references written by Fred (but not in 1991), plus all those by Joe.  This was generated by searching for Author Fred, then Narrow Search, select logical NOT and Date 1991, and finally Expand Search for Author Joe.


Adding a new reference
How to add a new reference

1.	Choose the database to which you wish to add the reference

2.	Choose Reference, New... or press F7.

3.	A dialog box will appear for you to enter author and date for the reference, as follows:

The Author field must be filled.  The UNIX refer format does not require this, but since the program usually sorts by Author name before sorting by year and then title, it's fairly important!  Besides, somebody must have written it!

4.	Select one of the option buttons for the document type.  Journal is the default (although this can be changed).  The only difference this makes is to save a %J, %B or %R field.  See technical notes for more information on UNIX refer file field identifiers.

5.	Choose OK

6.	A second dialog box will appear for you to enter the title, journal or book title as decided in Step 3, and notes for the current reference, as for editing a reference.


Editing or Viewing a reference
How to edit or view a reference

1.	Select the reference you are interested in and then select Reference, Edit...

Double-click on the reference you are interested in the main list or press F6.

The following screen appears:

2.	Choose Cancel to go back to the main list, or OK if you want the reference to be updated to its current displayed contents (i.e. if you've just edited it).  You can also choose OK and New which will update the current reference and go straight to a new author entry screen (as if you'd chosen OK and then Reference, New.

Choosing the buttons marked < and > moves to the previous/next reference in the currently active display.  It is equivalent to choosing Cancel and then double-clicking the neighbouring reference.

Note that you can add keywords from your keyword list with Reference, Add keywords.

NB:  You cannot edit or view a reference if more than one is selected in the main list.

Your most frequently used journals/book titles/reports are listed in the drop down combo box, so you can choose one with the mouse.  This encourages consistency.  See editing the common journal/book/report list.

If you wish to change the author, year or document type (book or journal) you cannot do this from the standard reference form you have just called up.  To do this, close the reference form and then:

Hold down Ctrl and double-click the reference, select Reference, Edit author...  or press F2.

Please note:

(a)	Windows® multi-line edit controls all allow carriage returns to be entered using Ctrl+Enter.  Do not do this!  If the field accepts carriage returns (without using Ctrl+Enter), then you may insert them.  In other fields, using Ctrl+Enter will cause confusion when saving the file, and text following the carriage return will be reloaded as part of the abstract!  Refs removes such inapprpriate carriage returns automatically.

(b)	If you wish to insert tab characters in your abstract field (or any other field), you must use Ctrl+Tab, since Tab alone moves the input focus to the next control in the dialog.

(b)	To enter unsupported fields such as %0 (other) just type them on a new line in the abstract field.  For instance if the abstract edit box when viewing the reference contains:

This is your abstract

%O spong

This will produce the correct refer file of:

%X This is your abstract.

%O other

Be careful of duplicating entries this way.  If you put a %T field in here, and your title field has something in it, both will be saved as %T lines.  When this is next loaded by Refs, the second %T entry (the one in the abstract) will be ignored and subsequently lost!  I don't know how other programs would behave.  This is the case for all duplicated fields, except %A (Author) and %E (Editor), which are duplicated for each name anyway.

(c)	The Keyword field should have your keywords on separate lines, without blank lines between them.  The same applies to the author field.  Each author should occupy a separate line with no blank lines.

(d)	Refs depends on the Journal/Book title/Report field to determine when loading what the type of the reference is.  Without this information, Refs will assume the reference to be from a journal when reading the file.


Deleting references
How to delete a reference

Select the reference(s) you wish to delete.

Then press Del(ete) or select Reference, Delete.  Depending on your options settings, Refs may ask you to confirm the deletion.  See list options for details.


Printing a reference
How to print references

You can print references from both editing windows and from file windows.

Edit window:

Choose Reference, Print and the viewed reference will be updated and then printed in the current bibliography format.

Database window:

Choose File, Print.  In the print dialog box that appears, you can choose to print either All or Selection.  The latter will be greyed if no references are selected in the current window.  Again. this prints the contents of the window in the current bibliography format.

References are printed in plain text.  No formatting options such as bold or italics are available.  However, you can select the font used for printing from the main Refs menu, under Options, Fonts, Printer.


Transferring information
Transferring information to/from other applications

Transferring information to word-processors is best done as follows:

1.	Add the references you want transferred to the bibliography

2.	Choose a format for display

3.	Display the formatted bibliography

4.	Edit it if you wish

5.	Select as much as you wish to copy from the bibliography window

6.	Choose Edit, Copy to place the selected information in the clipboard

7.	Now you can paste it into any application that supports text pasting from the clipboard (in other words, almost anything!)

8.	You can also use the Save as... option to save the entire formatted bibliography as a text file.  If you use a bibliography format that creates RTF files, you should save the file with the extension '.RTF', rather than '.TXT'  this can be used as a crude way of formatting your bibliography nicely for the word-processor.  However, in order to do this, you will need to know how to write RTF (not something I'd recommend to the faint-hearted!).

You can copy individual formatted references to the clipboard when viewing them; select Reference, Copy formatted.

You can also cut and paste directly to any edit box, in either the reference or author forms:

Select the text you wish to copy, or place the insertion point where you wish to paste.

Use standard Windows® Cut/Copy/Paste keys.  These are:

Cut:	Ctrl+X

Copy:	Ctrl+C

Paste:	Ctrl+V


Customising Refs
Customising Refs: The Options menu

Options, List format...

Options, Sorting...

Options, Auto view all  This option allows you to control whether Refs automatically displays the references for a file immediately after loading it.   This can take some time with large files.

Options, Input defaults...

Allows you to specify the default date used when creating a new reference, and the default source for references (book, journal or report).

Options, Confirmation...

This dialog controls whether Refs prompts you when you try to delete references, or drag them to another database window with the mouse.  These settings act globally.

Options, Fonts...  These three items allow you to define the font used by Refs for printing, the editing dialog and for displaying database windows.  The printer font is also used for displaying the formatted bibliography.

Options, Bibliography format... Choose how references will be formatted in the bibliography window.  See bibliography format syntax for details.

Options, Colour bibliography items... When a reference has been added to the bibliography, it changes colour in the main list.  Use this dialog box to choose what that colour should be.

Options, Language... Pops up a dialog asking you to choose which language DLL to use.  The language will change immediately.

Options, Default file format... This pops up a dialog asking you which file format you wish to use by default.  It presents you with a list of those filters installed that have both loading and saving capability.  At the moment only REFER.FLT has both, so this is the only file format available in this dialog.

Options, Save backups  Choose whether to make backup files when saving.


Bibliography format syntax

These formats are stored in REFS.INI (in Refs for Windows® 3.1), or in the HKEY_CURRENT_USER part of the Registry in the Windows NT™ and Windows® 95 version.

To create a new format, or change an existing one, choose Options, Bibliography format.  The following dialog will appear:

To create a new format choose New or to edit one select the format to edit and choose Edit.  Each format must have a unique name, and when creating a new one Refs will complain if you use a name that already exists.

A format line looks something like:

[prefix][suffix]<AN@, ><T@>\n< J@, ><V@><N/@ ><P@ ><D(@)>

Prefix and suffix sections:

There may be one (prefix only) or two (prefix and suffix) of these sections.  The characters inside these sections are attached at the beginning or end of the completed set of formatted references.  This is primarily for use in creating bibliographies in document processing languages, such as RTF or TeX.  If these are present, the [ character must be either (a) the first character in the format, or (b) immediately follow the ] of the prefix section.  Otherwise, Refs will begin interpreting as the main reference format string.  So:

[foo\n][bar] Hello.\n

Will format as:

foo

Hello.

.

.

.

bar

Whereas

[foo\n] [bar] Hello.\n

will format as:

foo

[bar] Hello.

.

.

.

How fields work:

The uppercase letters ABCDEIJKNPRTVX are the field tags  and have the same meanings as they do in the Refer file format.  See Technical notes for an explanation of the tag meanings.  They are mostly fairly self evident.  Once the field has been determined, the remaining characters are literally copied (with some exceptions, see Special characters below), so if your reference has Date field of '1992', <D(@)> will produce '(1992)' when formatted, and nothing if the date field is empty.

Fields begin with a <.  The next character must be a valid field tag character, or an exclamation mark.  If it is an exclamation mark, the next character must be the field tag, and then this field will only be formatted if the field is not filled.  If this field does or does not exist, as appropriate, in the reference, the other characters in the field will be printed until a > is encountered, otherwise parsing continues to the matching > character, so the field and any nested fields are missed out (see Nesting fields below).  The symbol @ indicates where in the field to insert the field text itself, unless the field tag was preceded by an exclamation mark, in which case the @ character itself is added.

Sub-formatting of Author and Editor fields:

The tag characters 'A' and 'E' may be followed by a number 1, 2 or 3, which correspond to the three Author formatting options available in the Main List Options dialog.  For example, <A1@> will list all the authors.

Fields can be nested.

For example:

<B@ <T@ , ><A1@, ><E2 Editor: @>>

is valid if you only want fields formatted like this if it's a book.  Nesting can be done to any level (within reason - you can run out of stack space if you do it too much).

Special characters:

To insert a carriage return in the string, use '\n'.

To insert a literal @, < or > without using their special function, precede them with a \.  \\ will produce a single \ in the formatted text.

Character formatting; bold, italics and so on:

There is no way to create bold or italic type, since Refs creates ANSI text, as used in Notepad.  However, if you are creating bibliography files for TeX, RTF or some other document processor that uses plain text source files it is possible, as long as you understand how they work!  I have included TeX and RTF example format lines.  The latter works well with most Windows® word-processors (it certainly works with Word for Windows), and should in theory allow you to put a formatted bibliography into any word-processor capable of reading Rich Text Format.  To do this yourself, you'll need to learn RTF, sorry!  You'll find descriptions of RTF in the documentation for most Windows® programming languages (because it's what Windows® Help files are written in).  I don't recommend doing a 'save as RTF' from Word and picking apart the output.  Such automatic conversions have loads of extra junk that just makes it hard to understand!

Long term plans are to change Refs so that it uses RTF itself to allow such formatting, but I don't really have the time for this at present.


Main display options
List Options Dialog

This dialog governs how the references are displayed in the main list; how wide the column for author names is, how many author names to display, and whether to also display the title of the reference.

The Select new items check box controls whether a newly created reference is automatically selected afterwards.

These settings are stored on a per window basis.  The last choices made determine those saved to your Refs configuration, and also will be the options the next created window will have.


Sorting Options Dialog
Sorting options

This dialog enables you to select how your references are sorted.

Refs will first makes comparisons between references on the basis of the first field.  If these are the same it will then try the second field and so on.

For each comparison you can choose which field to sort on, and whether you want ascending or descending order.  The default is to sort the way Refs used to, which is Author (Ascending), Date (Ascending), Title (Ascending).

As with the list options dialog box, these options are saved on a per-window basis, and the most recently given options are saved to the INI file and used to sort new files, and files being loaded.

There is a sub-dialog of this box, which you get by pressing the Names... button.  This changes settings on the way Refs interprets names in the author and editor fields.


Options for sorting names
Sorting by name

This dialog box gives some options that you can change to affect how Refs interprets and sorts by the names given for authors and editors.

As with the other sorting options, these options are stored on a per-window basis, and the most recently chosen options are used for defaults in new files and saved to your Refs configuration when you exit the program. The two radio buttons are the two main comparison methods:

First given name

This is how Refs used to sort all the time.  It is a plain comparison of the two author entries.  If you enter all your authors as, say 'Smith, J', then this will work perfectly for you.  It is very much faster than the next method.

Family name

Refs uses the remaining options to try to work out which word in the name is the family name, compare that first, and then compare the first name and/or initials.  First it checks whether you have explicitly put the family name first.  You do this by putting a separator in the name.  By default this separator is a comma, but it can be any single character other than a space or tab.  If Refs finds the separator, it assumes that everything before the separator is the family name, and everything after it is the first name and initials.  If Refs does not find the separator, it looks at the next option to see what to do next.

Examples

If you set 'surname usually last' and have a ',' separator Refs will interpret names as follows:

"Cutts, Tim" 	Family name: "Cutts" 	First name and initials "Tim"

"Tim Cutts" 	Family name: "Cutts" 	First name and initials "Tim"

"Cutts" 	Family name: "Cutts" 	First name and initials: none

Family name usually last

Refs looks at this setting to establish whether in  your language, you usually write the family name last (the English do, the Chinese don't, for example).  Either way, it assumes that the last or first word in the name, as appropriate, is the family name, and sorts on that basis.

NB:

Refs does not do this perfectly.  Refs will guess wrong for names like 'de Montfort' or others where there is more than one word in the surname.  Refs will see the family name (for sorting purposes, anyway) as 'Montfort'.  For such names you will have to put the family name first followed by a separator if you want it to be sorted by the first word of the family name.  Family names with hyphens, such as 'Fotherington-Smythe', do not have this problem.


Chemical Abstracts Import Notes
The Chemical Abstracts Import filter

This filter is only available with the 16-bit version of Refs, sorry.

The following notes are from the author of the Chemical Abstracts filter, Mats Valli:

Chemical Abstracts (CA) is not consistent in the way references to reports, books and patents are stored. Therefore only journals will be imported correctly, that is the Pages, Vol, VolNo and Journal are separated. For other types of references all this information is stored in the Journal field.  I will try to work this out in a later version.

When searching CA the following command should be issued before starting the search:

SET HIGHLIGHTING OFF

When displaying answers in CA the command D BIB ABS KW or D ALL should be used.

If data fields are longer than the filter allows they will be truncated and a message will appear saying so.

Amendments with version 1.11:

General options are:

Selective import - displays the next reference and asks whether it should be imported or not. The Import button imports the reference (:-)) and the Next button skips the reference and displays the next. The all button imports all remaining references and the Stop button stops importing new references. The one currently displayed will not be imported.

Cut bibliography - functions as before. If the import filter does not manage to cut the bibliographic data properly, deselect this option.

Truncation alert - If selected a warning message will appear if a data field must be truncated to fit within the allocated memory.

Keyword options are:

Source - The Chemical Abstracts volume reference will be included as a keyword.

Document type - The document type will be included as a keyword.

Language - The language, abbreviated CA-style, will be included as keyword.  '/LA' will be added to the abbreviated language code.  This makes it easy to include or exclude languages in a search.

Indexing terms - Besides using keywords, CA uses indexing terms.  These include the CA registration numbers for chemical compounds among other things.  The number of keywords will usually be much higher if the indexing terms are included.  This option requires that the references has been displayed by the command D ALL in the CA search.

Another enhancement involves the REFS.INI file. In the [NKW] section it is now possible to include one or more consecutive lines beginning with the keyword 'NotKeyWords='.  All words, separated by a blank, listed after the equal-to sign will be excluded as keywords.  Indexing terms (see above) usually include words like 'and', 'or' and 'from'.  These can now easily be excluded from being imported as keywords.

NB. The file to be imported may not contains results from File Registry in CA. If it does, the filter will not work properly.

Mats Valli	E-mail: mats@sunsp1.sc.fukuoka-u.ac.jp


Editing the Common Lists
Editing the Common Journal, Book and Report Lists

While viewing or editing a reference, select Edit, Common Journals... or the appropriate menu command for the list you wish to edit.  A dialog box will appear, as follows:

Selecting an existing entry in the list will copy it into the edit box below the list.  You can either choose the Delete button to get rid of it from the list (though it stays in the edit box in case you change your mind), or you can edit it and press Change to replace the original version in the list box.

Thirdly you can press Add to add the new item to the list without affecting those already there.

Choosing OK will save the new settings to your Refs configuration.  It will also update the combo box in the editing window if you change the list for the current reference type.  In this case you will lose any changes you made to the journal/book title before editing the list.


Adding keywords
Adding keywords to references

Most people like to have a set of standard keywords which they use again and again.  This makes searching for references on a certain topic very fast and effective.  Refs provides you with the following dialog box for this purpose:

The Add Keywords dialog serves two purposes:

1)  Adding keywords to one or more references.

2)  Updating the keyword list

To add a new keyword to the list, type the keyword in the edit control at top right, and then click the Add button.  This puts the keyword in the list but not in the reference.

You can generate a list of all the keywords in the current file by choosing Scan active file.

Choosing Save list will write the contents of the list box to your Refs configuration as your keyword list.

If one or more keywords are selected you can choose the Delete button to remove them from the list.

If you wish to edit a keyword, select it, and choose the Edit button.  It will be removed from the list and placed in the edit box for editing.  Choose Add to put it back when you are ready.


Technical notes

This program was originally written in Turbo Pascal for Windows 1.5, and was translated into C++  from version 7.8.  It requires Windows® 3.1 or higher to run.  You may also be running a version requiring Windows® 95 or Windows NT™ 3.51 or later

It is written to be easily converted to other (human) languages.  Please see the language page of this help file for details.

Capacity of the Windows 3.1 version

Each open database has a maximum capacity of 262,140 references in Standard mode, and something over 4.1 million references per database window in 386 Enhanced mode.  You will certainly run out of memory before reaching this limit! The About box in the program tells you how much memory is free.

There are other restrictions, unfortunately, imposed by Windows 3.x.  You are only allowed 8,192 entries in a List Box, so searches going over that will stop being displayed when the list box is full, though they will still be in the search results.  You should also be aware that displaying all the references can take some time with large files (of several hundred references or more).  Also, because of the limit on edit controls of 32k, this is the maximum size your formatted bibliography can be.

These limits are not present if you are using the version specially compiled for Windows NT and Windows 95.  However, having such large files is not a good idea; over a few hundred entries the screen display becomes very slow to update.

At present I have arbitrarily imposed a maximum length of 16K to each field.  This should be enough for most purposes, I hope!

Files are saved by default in the common UNIX refer format.  This means that databases created by this program can be used with UNIX refer, and bibliography programs such as WinRefer.  The order of fields in this file format is not important.

Refer fields currently supported explicitly by Refs are:

%A	Author

%T	Title

%J	Journal

%B	Book title

%R	report (used for unpublished documents)

%I	Publisher

%C	City of publication

%E	Editor

%V	Volume

%N	Number in volume

%P	Pages

%D	Date

%X	Abstract

%K	Keywords

The above meanings are as described in SunOS 4.1.3 manpage refer(1)

Fields not included in the above list can still be entered in the database;  see editing references.

The major fields not covered explicitly are:

%O	other (appended)

%Z	ignored

Such fields, when encountered in files, will appear in the abstract field, but will be saved correctly.  If anyone knows of other less common fields (those listed here are all the ones I know about), I would be glad to learn about them.

Foreign file format filters are loaded at run-time.  The filter interface structure is included in this help file for any programmers wishing to write one.


Running Refs on a network

By default, Refs for Windows 3.x places its REFS.INI file in the same directory as the executables.  Obviously on a shared server filesystem this presents a problem - either the directory is read-only, and no-one can change their settings, or it's world-writeable, and everyone changes the settings for everyone else.  If you're running Refs in such a situation. Make sure that users have a copy of REFS.INI in their Windows directory.  Refs always looks there before looking in the default location.

Users of the 32 bit version of Refs do not need to worry, since in this version the configuration information is all stored in the user's personal Registry settings.  There are some default example bibliography formats in HKEY_LOCAL_MACHINE which are copied to the user's settings if the user has no formats of their own yet.


Duplicate references

Refs is very strict about duplicate references; it tries to prevent them occurring at all costs.  This can cause problems

Refs checks that using the current sorting method, the references do not appear to be the same (after all, why would you want the same reference twice in one file?).

If this test shows a potential duplicate, Refs pops up a dialog.  You have four choices:

1)  You can choose not to include the reference in the target database (Don't include).

2)  You can Overwrite the previous copy.

3)  You can edit it so that the sort mechanism no longer sees it as a duplicate.

4)  You can abandon the entire operation.  This is useful if the duplicates are arising because you have an inappropriate sorting method selected, or because you have opened a file of the wrong format.


Refs and other languages
Refs and other (spoken) languages

Refs has been designed to cope well with using languages other than English.  All its sorting and searching uses your Windows language setting so that sorting is appropriate for your language.

All language dependent resources such as messages, menus and dialog boxes are stored in a separate DLL.  When initially installed there is no Language setting in your REFS.INI file.  In this case, Refs reads your WIN.INI file [intl] sLanguage entry to establish which DLL to use.  If it does not have a suitable DLL it defaults to English.  At present, REFEN.DLL (English), REFES.DLL (Spanish), REFDEU.DLL (German) and REFJPN.DLL (Japanese) are available, but I hope to have DLLs for other languages, particularly French and Italian, and would greatly appreciate any user's help in creating them.

Refs checks that the DLL in use is the correct version for the main program.  It will allow other versions to be used, but issues a warning.

Of course such DLLs need not be used just for foreign languages.  With careful re-writing of resources, customisation of Refs for completely different or specialised purposes is possible.

Gerald Pfeifer (e9025064@student.tuwien.ac.at), the German translator, says:  "If you're using the German DLL please feel free/encouraged to contact me with suggestions, remarks, and bugs!"

If you do find a bug in the non-English versions, please contact the author of the DLL in question in the first instance, rather than the author of Refs itself..


Import DLL structure
Import/Export filter structure and interface

Import/Export filters are normal Windows Dynamic Link Libraries consisting of at least two exported functions.  Two functions are compulsory, the rest are optional.  The compulsory functions are as follows:

WhoAmI()

GetSpecs()

Refs uses these functions to obtain data about your library - its description and the type of files it loads and saves.

The optional functions are as follows.  Obviously at least one of LoadRef() and SaveRef() should be present, otherwise your filter won't do much!

LoadRef()

SaveRef()

Opts()

The Opts function, if it exists, can be used by the user to modify the way your library behaves.

There is a library of helper functions supplied with Refs, called RIMPEXP.DLL, which you may find useful in writing your filters.

The resulting DLL should then be renamed to have a file extension of FLT so that Refs will recognise it.  Please upload any import filters you write... others might find them useful!  Or send them to me, and I will include them in the next official release of Refs.


WhoAmI import DLL function
LPSTR FAR PASCAL WhoAmI(void);

This returns a pointer to a null-terminated string describing the filter.  This is the string that gets inserted in the choices list box.


GetSpecs import DLL function
LPSTR FAR PASCAL GetSpecs(void);

This returns a pointer to a special string that will be referred to in the lpstrFilter member of a TOPENFILENAME structure that will be passed to GetOpenFilename() or GetSaveFilename().  See  your compiler documentation for details.  The old 16-bit BIDS.FLT had the following code for this function:

function GetSpecs: PChar; export;

begin

  GetSpecs := 'ISI text file (*.isi)'+

    #0+'*.ISI'+#0+'All files (*.*)'+#0+'*.*'+#0#0;

end;

The C equivalent used by the Refs 7.8 version is:

#ifdef WIN32

LPSTR _declspec(dllexport) GetSpecs(void){

#else

LPSTR CALLBACK _export GetSpecs(void){

#endif

  return "ISI text file (*.isi)\0*.ISI\0All files (*.*)\0*.*\0\0";

}


LoadRef import DLL function
TImportRef FAR * PASCAL LoadRef(HWND Aparent; LPMMIOINFO FS; LPSTR INIPath);

FS is a far pointer to a MMIOINFO structure (see win31mwh.hlp and/or mmsystem.pas/mmsystem.h for more details).

The file FS->hmmio will have been opened for buffered I/O and an internal buffer will have been allocated with mmioSetBuffer().  You can retrieve the size of this buffer with the function GetBufSz().  LoadRef must load a single reference, and fill a TImportRef structure with it.  You then return a pointer to this structure.  Refs will copy the data, so you may dispose of it in another procedure (or next time LoadRef is called, which is the way both BIDS.FLT and MEDLINE.FLT do it).  LoadRef is repeatedly called by Refs until you return a non-zero Result member of the TImportRef.  Do not close the file.  Refs will do this for you.

Your function is responsible for calling mmioAdvance() when appropriate to update the buffer as you read from it.  mmioAdvance() has not been called before LoadRef is first called.  Example code in both Pascal and C can be obtained from the Refs WWW site.  See the introduction.

If you need to load any options, INIPath gives the path to REFS.INI

Obviously, Pascal programmers will need to add 'MMSystem' to their uses clause, and C programmers will need to #include <mmsystem.h>.

Important changes in Refs 7.8

The INIPath parameter is not present in the 32 bit version.  Use GetConfigStr() and so on from RIMPEXP.H instead to set your configuration options.


Opts import DLL procedure
void FAR PASCAL Opts(HWND Aparent, LPSTR INIPath);

This is your options procedure.  If this procedure is not present, Refs will display a message box to the user saying so when the Options button is chosen, otherwise Opts is called, and you are free to display an options dialog box for your filter, using AParent which is the REFS.EXE main window handle.  Bear in mind that your filter will be freed before being used again to import a reference, so any options should be saved to an INI file.  You may use REFS.INI for this purpose.  The path to REFS.INI is given by INIPath.

Important changes in Refs 7.8

The INIPath parameter is not present in the 32 bit version.  Use GetConfigStr() and so on from RIMPEXP.H instead to set your configuration options.


TImportRef import DLL structure
struct TImportRef

This is declared in imptfr.h or imptfr.inc, both of which are components of the Refs Development Kit.

struct TImportRef {

  BYTE Result;

  BYTE RefType;

  LPSTR Authors, Date, Title;

  LPSTR Journal; /*Or book title, depending on RefType*/

  LPSTR Vol, VolNo, Pages;

  LPSTR Text; /* Abstract*/

  LPSTR Keywords, Publisher, City, Editor;

  LPSTR SortStr;

};

Result should be filled as follows:

0	Reference read, file not yet exhausted, carry on reading

1	Reference read successfully, and end of file reached, stop reading

>1	Error, stop reading, do not create a reference from this TImportRef.

RefType:

0	Journal (%J)

1	Book (%B)

2	Report (%R)

Other values will result in problems.

The other entries should contain pointers to null-terminated strings, or NULL.  There are some rules:

Keywords and Authors fields:

The individual items should be separated by CRLF, otherwise Refs will make errors saving and displaying the references.

SortStr is ignored, at present.  Refs will fill this itself, after copying the structure.


SaveRef() filter function
int FAR PASCAL _export SaveRef(HWND aparent, TImportRef *Ref, MMIOINFO *FS, char *INIPath);SaveRef

SaveRef is passed a TImportRef structure.  Your task is simply to write the contents of that structure to the MMIO file passed in FS.  Simple, honest.

Important changes in Refs 7.8

The INIPath parameter is not present in the 32 bit version.  Use GetConfigStr() and so on from RIMPEXP.H instead to set your configuration options.


RIMPEXP.DLL library functions
 RIMPEXP.DLL:

Helper functions for Import/Export filters

This is a somewhat limited library at present, but there are at least a few functions to stop you from having to reinvent the wheel.

File reading/writing:

GetBufSz()

SetBufSz()

ReadLine()

WriteLine()

vMMIOprintf()

Configuration editing:

GetINIFilePath() (16 bit versions only)

GetConfigStr()

SetConfigStr()

GetConfigInt()

SetConfigInt()

DeleteConfigTree()


WriteLine
int FAR PASCAL WriteLine(LPMMIOINFO FS, LPSTR text);

WriteLine() writes the null terminated string text to the file specified in FS.  It does not append a CR/LF to the line.  It returns 0 if it simply wrote the text to the buffer.  It returns -1 if text is NULL.  If it called mmioAdvance() in the process of writing text to the buffer, it returns the code returned by mmioAdvance().


vMMIOprintf
int FAR PASCAL vMMIOprintf(LPMMIOINFO FS, LPSTR format, va_list args);

vMMIOprintf() is a wrapper around WriteLine().  It behaves in exactly the same way as vfprintf() or vsprintf(), and returns the same values as those functions.


ReadLine
BOOL FAR PASCAL ReadLine(LPMMIOINFO FS, LPSTR text, BOOL FAR *EoF);

ReadLine() reads a single line from FS into text.  text should be at least as large as the value returned by GetBufSz(), to avoid possible general protection faults.  The terminating CRLF pair is discarded by ReadLine, so you won't see them.

The return value is not particularly useful, but the functions sets EoF when the end of the file has been reached.


GetBufSz()
long FAR PASCAL GetBufSz(void); long FAR PASCAL SetBufSz(long);

GetBufSz() returns the size of the buffer Refs is using in the MMIOINFO structure.

SetBufSz() sets the size of the buffer.  There is no reason to call this function from within your filter - it is called by Refs before loading your library, and a buffer set.  Calling the function again simply returns the current buffer size, just like GetBufSz().


GetINIFilePath()
LPSTR FAR PASCAL GetINIFilePath(void);

GetINIFilePath() is only available in the 16 bit version of RIMPEXP.DLL.  The 32 bit version uses the Registry, rendering this function redundant.


RIMPEXP.DLL: Configuration functions
Configuration manipulation functions

These are a set of functions to give you a consistent source code interface across the 16 and 32 bit versions of Refs, transparently setting configuration options in REFS.INI or the Registry respectively.  The syntaxes are in general very similar to the PrivateProfile() functions in the Win16 API.

int GetConfigInt(LPSTR Key, LPSTR Value, int Default);

In all these functions, in Win32 systems, Key will be added to HKEY_CURRENT_USER\Software\Refs\ to set the location in the Registry.  In 16 bit Windows, Key is the section of the INI file to be used.

GetConfigInt() returns the value found in the configuration data, or the Default if the data was not found.

int GetConfigStr(LPSTR Buf, int szBuf, LPSTR Key, LPSTR Value, LPSTR Default);

GetConfigStr() returns the length of data copied in to Buf.  szBuf should contain the size of Buf.  If the data requested is not found, Default is used.

void SetConfigInt(LPSTR Key, LPSTR Value, int Quantity);

Hopefully self evident!

void SetConfigStr(LPSTR Key, LPSTR Value, LPSTR Data);

SetConfigStr() behaves much like WriteProfileString(); if Data is NULL, the Value entry is deleted.

void DeleteConfigTree(LPSTR Key);

This function deletes entire Registry subtrees.  Use with care!


Refs Development Kit
The Refs Development Kit

This contains example source code for Import/Export filters and all the header files, import libraries and units required to write such libraries in both C/C++ and Pascal.  Contact the author for details.


Frequently Asked Questions

These are the most commonly asked questions about Refs.  Please read these before mailing me!

Crashes

Help!  Refs caused a GPF in module XXX.FLT!  Is this a bug in Refs?

Formatting

How can I put bold and italics in my documents?

Importing data

Refs won't import my MedLine literature search!  Why not?

Refs still won't import my foreign data!

I got a REF file from a friend and all the foreign characters are wrong!

Miscellaneous

Refs only has three document types - can we have some more?

Refs won't let me change my document type!  It keeps resetting to 'Journal'.  Why?

You haven't answered my question!


Bold and Italics
How can I put bold and italics in my documents?

The simple answer is that you can't.  Refs uses a plain ASCII text file format that originally came from the UNIX world.  There is no provision for character formatting, and there probably never will be.  This is not quite the end of the story, though.  There are plain text description languages that allow such formatting.  Examples are Rich Text Format and TeX.  It is possible to persuade Refs to output formatted text in these formats by writing appropriate bibliography format lines.  Examples are supplied in the standard REFS.INI files.  If you save your formatted bibliography as FOO.RTF you could then load it into Word for Windows, for example, and Word will recognise the RTF and format the text appropriately.  This does however require some knowledge of RTF, which is hairy for newer computer users, but pretty straightforward for people who remember the archaic days of CP/M and pre-Windows word-processors.

Windows 95 and Windows NT 3.51 have an RTF edit control.  This makes it quite likely that this functionality will be added to the 32-bit version of Refs.


MedLine Problems
Refs won't import my MedLine literature search!  Why not?

Sigh.  I loathe MedLine.  There are two possible causes.  First of all, you must ensure that the file you are reading is a genuine MedLine database file.  Don't try to import the output of the search as formatted for human eyes; you can read it, but MEDLINE.FLT can't!  The filter requires raw MedLine data.  The second reason is that there are many minor variations on MedLine.  I have tried to cater for some of them as they have cropped up, but this is an ongoing process.

See also text file problems.


Text File Problems
Refs still won't import my foreign data! (text file problems)

Computer scientists are a contrary lot, and they like designing things to be incompatible.  You could be having problems with incompatible text file formats, especially if you are transferring the data from a Macintosh or UNIX machine.  The sad thing is that DOS, UNIX and MacOS all use different ways to mark the end of a line in a text file, and you need some little programs to convert them properly if things have gone wrong.

Macintoshes end their lines with a carriage return.

UNIX ends its lines with a line feed.

MSDOS, Windows NT and OS/2 end their lines with both.

Included with Refs are two teeny programs. MAC2DOS.EXE and UNIX2DOS.EXE, which will convert your files for you.  They are filters like MORE, so you should use them as follows:

MAC2DOS < MACFILE.TXT > DOSFILE.TXT

or

TYPE MACFILE.TXT | MAC2DOS > DOSFILE.TXT

This conversion should normally be applied to files automatically by ftp programs or Apple File Exchange, but other transfer methods do not always do it.  The filters will not modify a file in the correct format, so you can use them all the time.


GPF in module XXX.FLT
Help!  Refs caused a GPF in module XXX.FLT!  Is this a bug?

Not necessarily.  Most of the import filters are fairly simple, and if you feed them the wrong sort of file, they will crash.  If the message says in module XXX.FLT' rather than in module REFS.EXE', then that means that the crash occurred while the filter code was executing, even though it says REFS.EXE caused the fault (it only says that because REFS.EXE 'owns' the filter that crashed).  So, if you're sure your file format is correct, and you're still getting the crash, hassle whoever wrote the filter rather than me, since it's not Refs' fault!


Document Types
Refs only has three document types - can we have some more?

Here we are again bound by the Refer file format, I'm afraid.  Refer only has three document title types (which is how Refs determines what sort of document it is).  These are %J, %B and %R.  There can't be any more since this would make Refs refer support non-standard.  Now, there is a solution to this, and many of the import filters will do it for you automatically when reading a new file, and that is that they will include the document type field of the foreign file as a keyword.  Then you can search by keyword for reviews, or whatever.


Can't Change Document Types
Refs won't let me change my document type!  It keeps resetting to 'Journal'.  Why?

This is a problem with the way the refer file format, that Refs uses, works.  There are two title fields; %T and one of %B, %J and %R, depending on the document type.  In the editing window the main title box sets the %T field.  The smaller one below it sets %J, %B or %R according to reference type.  The idea is that this arrangement is useful for listing  chapters in a book.  The chapter title goes in %T, and the volume it's in %B.  If you just put a book title in %T, and nothing in %B, Refs will save the file without a B, J or R record for that reference.  When it comes to read the file again, it will not be able to determine the document type, since it normally keys on the existence of a B, J or R field, so it assumes J.

You just need to make sure that the book title always goes in the smaller field.  This is not a problem with searches or displaying titles, because Refs searches or displays the small title field instead if the %T field is empty.


Other Questions
You haven't answered my question!

You need to contact me.  See the entry About the author'.


Foreign accented characters corrupted!
My non-English accented characters are corrupted!

If you get a Refer file that contains accented characters these may not display properly.  The cause of this is that DOS-based programs do not use the same character codings as Windows.  Open the File, Import dialog box.  Select the Refer format and click the Options button.  In the dialog there is a checkbox for OEM to ANSI character conversion.  You should select this if you are reading files created by a non-Windows program, or when saving files for export to a non-Windows program.  The rest of the time you should leave it switched off;  the ANSI character set is rather better for accented characters, and having the conversion enabled slows Refs down when saving and loading files.